开发者文档

AnPay JSON-RPC API

通过一套 JSON-RPC 2.0 接口即可接入全球代收与代付。所有请求 POST 到统一端点,方法名写在 method 字段,资金流转全程上链、可对账。

接入端点 ({{ epLabel }})

POST {{ epUrl }}

鉴权

每个请求带四个请求头。密钥在商户后台「API 密钥」页创建(沙盒 / 生产各自独立),secret 只在创建时显示一次。

HTTP Header

Content-Type:      application/json
X-AnPay-Key:       ak_live_8f2a••••••••3c7d
X-AnPay-Timestamp: 1785340921034        // epoch 毫秒,偏差 > 5min 拒绝
X-AnPay-Nonce:     3f9c1a…              // 随机串,防重放
X-AnPay-Sign:      HMAC-SHA256(secret, TIMESTAMP + "\n" + NONCE + "\n" + RAW_BODY)

签的是 body 的原始字节。反序列化后重新 JSON.stringify 会改变键序与空格,签名必然对不上 —— 请在中间件里留一份 raw body。另可在后台为密钥配置 IP 白名单。

请求与响应格式

遵循 JSON-RPC 2.0:成功返回 result,失败返回 error,始终回传对应 id。HTTP 状态码恒为 200,业务结果只看有没有 error。金额一律用字符串传递 —— JSON 的 number 是双精度浮点,大额或 18 位小数会丢精度。

成功响应

{
  "jsonrpc": "2.0",
  "result": {
    "no": "P-20260726-0431",
    "status": "reviewing"
  },
  "id": "c-8842"
}

错误响应

{
  "jsonrpc": "2.0",
  "error": { "code": 40201,
    "message": "insufficient balance",
    "data": { "balance": "12.000000",
              "required": "100.500000" } },
  "id": "c-8842"
}

error.code 是五位数,首三位镜像 HTTP 语义:401xx 鉴权 · 400xx 参数 · 402xx 余额与限额 · 429xx 限流 · 500xx 服务端。JSON-RPC 保留的负数只用于协议层错误(如 -32601 method not found)。请按 error.data 里的结构化字段排查,不要去解析 message —— 文案会改,字段不会。

方法参考

全部 POST /api/v1/rpc,方法名写在 method 里。枚举对外一律出字符串,单号只出 no。

{{ m.grp }} {{ m.method }} {{ m.desc }}

提示 {{ m.note }}

参数

{{ p.name }} {{ p.type }} {{ p.desc }}

示例请求

{{ m.example }}

示例响应

{{ m.resp }}

Webhook 回调

状态变化时,AnPay 向你配置的回调地址 POST 事件,签名方式与请求一致(同一把 secret)。成功的判定是 HTTP 200 且 body 为 ok;否则按 1m / 5m / 15m / 1h / 6h 指数退避重试,共 8 次后放弃。每个事件带唯一 event_id,请据此去重。

{{ w.event }} {{ w.desc }}